/*
Copyright (c) 2009-2010, Warwick Warp Limited
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of the Warwick Warp Limited nor the
      names of its contributors may be used to endorse or promote products
      derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL WARWICK WARP LIMITED BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/

/*!
	\mainpage
	
	\section introduction Introduction
	
	woptions is a library built to make command line parsing easier and more 
	elegant in C++. There are many alternatives, but this is ours. The main aim 
	of woptions is to provide an interface that is easy to remember, easy to use 
	and easy to read.
	
	\section skeleton Skeleton Usage
	
	Typical code looks something like this
	
	\code
	#include "woptions/woptions.h"
	
	class Options : public woptions::ProgramOptions
	{
	public:
		Options()
		{
			// Bind argument and options...
		}
	};
	
	int main(int argc, char *argv[])
	{
		Options opts;
		try
		{
			opts.parse(argc,argv);
		}
		catch(const woptions::ArgumentException& e)
		{
			opts.usage(argv[0]);
			std::cerr << e.what() << std::endl;
			return 1;
		}
	}
	\endcode
	
	\see major
	
	\section arguments Arguments
	
	You would then populate the Options constructor with various binders for 
	options and arguments. To bind arguments (that is to say anything not 
	associated with a switch) we use the Options::argument and 
	Options::arguments functions:
	
	\code
	argument(description, binder);
	argument(description, woptions::bind_argument_ignore());
	argument(description, woptions::bind_argument_var(m_variable));
	argument(description, woptions::bind_argument_fun(my_function));
	argument(description, woptions::bind_argument_mem_fun(my_class,my_function));
	
	arguments(description, min_count, binder);
	
	arguments(description, min_count, max_count, binder);
	\endcode
	
	The first form is a general form, binder can be any function-class that 
	takes a std::string as its parameter. The four binders provided with 
	woptions are for ignoring the argument, casting to a variable (using 
	std::istringstream), calling a unary function (with any argument type, 
	woptions automatically figures out the argument type and casts using 
	std::istringstream) and calling a member unary function (again with any 
	argument type). The Options::arguments forms can be used to bind a variable 
	number of arguments to a particular binder. For example, we can push all the 
	arguments on to the back of a vector with one line:
	
	\code
	class Options : public woptions::ProgramOptions
	{
	public:
		Options()
		{
			arguments("arg",0,woptions::bind_argument_mem_fun(&m_args,&std::vector<std::string>::push_back));
		}
		
		std::vector<std::string> m_args;
	};
	\endcode
	
	Note the use of the 'ProgramOptions' class to avoid having to bind arg0.
	If we only accepted ints, then we could do that as well:
	
	\code
	class Options : public woptions::ProgramOptions
	{
	public:
		Options()
		{
			arguments("int",0,woptions::bind_argument_mem_fun(&m_args,&std::vector<int>::push_back));
		}
		
		std::vector<int> m_args;
	};
	\endcode
	
	and woptions would figure out what to do.
	
	\see cargbind, wargbind, gargbind
	
	\section options Options
	
	Any argument starting with a hyphen is considered an "option". We can bind 
	options as follows:
	
	\code
	option("-a","","Option with no arguments.",binder);
	option("-b","(#)","Option with 1 argument",woptions::bind_option_var(m_variable));
	\endcode
	
	As with arguments we specify a binder to handle the option when it is encountered,
	there are binders for setting variables, calling functions (or member functions) 
	with up to 3 arguments (of any type) and for setting variables to a specific 
	value. All the binders derive from woptions::bind_option to expose more 
	functionality than argument binders (for example, binding to a member variable 
	will automatically display the default value of that variable).
	
	Note that a single hyphen is not considered an option (for example, some 
	programs might use this to represent standard input or standard output).
	
	\subsection Single Argument Options
	
	If an option is parsed but not registered, woptions tries to parse it as a 
	single argument option. Single argument options can also be passed using two 
	additional syntactical forms. For options which are a single character it 
	is possible to do:
	
	\code
	-X(value)
	\endcode
	
	For example, the -I option to gcc. Alternatively it is possible to do
	
	\code
	-option=(value)
	\endcode
	
	with the first equals sign being used to separate the option name from its 
	value.
	
	\subsection Flags
	
	An option which takes no arguments and consists of a single character after
	the hyphen (other than another hyphen) is considered to be a "flag". 
	Whenever an option cannot be parsed normally or as a single argument option 
	woptions tries to parse the option as a sequence of flags. For example, we 
	could register options with
	
	\code
	option("-a","","Set flag a.",woptions::bind_option_value(m_a,true));
	option("-b","","Set flag b.",woptions::bind_option_value(m_b,true));
	\endcode
	
	then woptions would parse the command line
	
	\code
	program -ab
	\endcode
	
	as though the user had typed
	
	\code
	program -a -b
	\endcode
	
	\see coptbind, woptbind, goptbind
	
	\section Argument Transformations
	
	The library also supports some transformations that can be applied to 
	command line arguments. For example, we can substitute an argument with 
	arguments read from a file using the woptions::read_from_file 
	transformation in an overloaded version of parse:
	
	\code
	using woptions::Options::parse; // for overloads
	void parse(const std::vector<std::string>& args)
	{
		std::vector<std::string> all_args = args;
		read_from_file t;
		t(all_args);
		
		Options::parse(all_args);
	}
	\endcode
	
	\see argtrans
	
	\section example_cp Example: cp
	
	\include cp.cpp
*/

/*! \defgroup traits   Option Traits              */
/*! \defgroup major    Major Classes              */
/*! \defgroup coptbind Option Binders (char)      */
/*! \defgroup woptbind Option Binders (wchar_t)   */
/*! \defgroup goptbind Generic Option Binders     */
/*! \defgroup cargbind Argument Binders (char)    */
/*! \defgroup wargbind Argument Binders (wchar_t) */
/*! \defgroup gargbind Generic Argument Binders   */
/*! \defgroup argtrans Argument Transformations   */

#ifndef WOPTIONS_WOPTIONS_H_INCLUDED
#define WOPTIONS_WOPTIONS_H_INCLUDED

#include "argumentexception.h"
#include "option_binders.h"
#include "argument_binders.h"
#include "argument_transforms.h"
#include "options.h"
#include "programoptions.h"
#include "utf8_traits.h"

#endif

